livecodefandomcom_de-20200214-history
BinaryDecode
Decodesbinary data and places it into the specified variables.Syntax: binaryDecode(, , ) Examples: binaryDecode("h","M",theHex) -- converts M to its hex equivalent binaryDecode("a*",receivedData,textData) -- converts data to text binaryDecode("x12Sh16",picHeader,junk,numColors,colorTable) binaryDecode(myFormat,placeHolder,importantStuff) Use the binaryDecode function to convert binary data into a form that can be manipulated by handlers. The binary data format used by binaryDecode is similar to the format produced by the "pack" function of the Perl programming language. You must declare or otherwise create all variables in the variablesList before using them in the binaryDecode function. Unlike the put command, the binaryDecode function does not automatically create local variables when you use them. Although the x dataType skips the specified number of bytes rather than converting them, you still must provide a variable for instances of x that appear in the formatsList. The binaryDecode function does not change the value of a variable used for the dataType x. If the formatsList specifies fewer bytes than are in the data, the binaryDecode function ignores the remaining bytes. If the formatsList specifies more bytes than are in the data, the binaryDecode function converts as many of the dataTypes as there is data for. Check the value that the binaryDecode function returns to determine how much data was actually converted. Here is an example: on convertStuff dataToConvert global headerData,placeholder,bodyData,footerData put binaryDecode("i5x2a24xi2",dataToConvert, \ headerData,placeholder,bodyData,placeholder,footerData) \ into convertResult if convertResult < 3 then return "Error: data was corrupted" end convertStuff Parameters: *formatsList: The formatsList consists of one or more dataTypes, each followedoptionally by an amount. A dataType is one of the following singleletters: x: skip next amount bytes of data *data (string): A string of encoded binary data. *variablesList: A comma-separated list of local or global variable names. The number ofvariable names must be the same as the number of dataTypes specified inthe formatsList, and the variables must already exist. *amount: a: convert next amount bytes of data to charactersA: convert next amountbytes of data (skipping spaces) to charactersb: convert next amount bitsof data to 1s and 0sB: convert next amount bits of data to 1s and 0s,starting at the high end of each byteh: convert next amount bytes ofdata to hexadecimal digitsH: convert next amount bytes of data tohexadecimal digits, starting at the high end of each bytec: convert nextamount bytes of data to signed 1-byte integersC: convert next amountbytes of data to unsigned 1-byte integerss: convert next amount 2-bytechunks of data to signed integers in host byte orderS: convert nextamount 2-byte chunks of data to unsigned integers in host byte orderi:convert next amount 4-byte chunks of data to signed integers in hostbyte orderI: convert next amount 4-byte chunks of data to unsignedintegers in host byte ordern: convert next amount 2-byte chunks of datato signed integers in network byte orderN: convert next amount 4-bytechunks of data to signed integers in network byte orderm: convert nextamount 2-byte chunks of data to unsigned integers in network byteorderM: convert next amount 4-byte chunks of data to unsigned integersin network byte orderf: convert next amount 4-byte chunks of data to asingle-precision floatd: convert next amount 8-byte chunks of data to adouble-precision floatThe amount corresponding to each dataType is aninteger or the * character. If no amount is specified, the dataType isused for a single byte of data. The * character causes the rest of thedata to be converted according to the formatType, so it should appearonly as the last character in the formatsList.]]*Important:* If youspecify an amount with a string dataType (a or A), the binaryDecodefunction places amount bytes in the next variable of the variablesList.If you specify an amount with a numeric dataType, the function placesamount chunks of data in the next amount variables of the variablesList.For example, the dataType "a3" requires only one variable, which willhold a 3-characterstring, but the dataType "h3" requires threevariables, each of which will hold a single hex digit. *Returns: The binaryDecode function returns the number of dataTypesthat were successfully converted and placed in variables (notcounting data skipped by the x dataType). The actual data is placed inthe variables, rather than returned by the function. See also: numToChar (function),format (function),value (function),